package com.kexio.enterprise.observability.metrics;

import com.kexio.enterprise.observability.metrics.domain.ApplicationMetrics;
import com.kexio.enterprise.observability.metrics.domain.SystemMetrics;
import com.kexio.enterprise.observability.metrics.enums.ExportFormat;
import com.kexio.enterprise.observability.metrics.statistics.DistributionStatistics;
import com.kexio.enterprise.observability.metrics.statistics.TimerStatistics;
import com.kexio.enterprise.observability.metrics.timer.TimerSample;

import java.util.Map;
import java.util.Set;

/**
 * 指标收集服务接口
 * 
 * 提供应用性能指标的收集、聚合和查询功能
 * 
 * @author Kexio
 * @since 1.0.0
 */
public interface MetricsService {

    /**
     * 增加计数器
     * 
     * @param name 指标名称
     * @param tags 标签
     */
    void incrementCounter(String name, Map<String, String> tags);

    /**
     * 增加计数器（指定增量）
     * 
     * @param name   指标名称
     * @param amount 增量
     * @param tags   标签
     */
    void incrementCounter(String name, double amount, Map<String, String> tags);

    /**
     * 记录计量器值
     * 
     * @param name  指标名称
     * @param value 值
     * @param tags  标签
     */
    void recordGauge(String name, double value, Map<String, String> tags);

    /**
     * 记录计时器
     * 
     * @param name     指标名称
     * @param duration 持续时间（毫秒）
     * @param tags     标签
     */
    void recordTimer(String name, long duration, Map<String, String> tags);

    /**
     * 记录分布统计
     * 
     * @param name  指标名称
     * @param value 值
     * @param tags  标签
     */
    void recordDistribution(String name, double value, Map<String, String> tags);

    /**
     * 记录直方图
     * 
     * @param name  指标名称
     * @param value 值
     * @param tags  标签
     */
    void recordHistogram(String name, double value, Map<String, String> tags);

    /**
     * 获取计数器值
     * 
     * @param name 指标名称
     * @param tags 标签
     * @return 计数器值
     */
    double getCounterValue(String name, Map<String, String> tags);

    /**
     * 获取计量器值
     * 
     * @param name 指标名称
     * @param tags 标签
     * @return 计量器值
     */
    double getGaugeValue(String name, Map<String, String> tags);

    /**
     * 获取计时器统计
     * 
     * @param name 指标名称
     * @param tags 标签
     * @return 计时器统计
     */
    TimerStatistics getTimerStatistics(String name, Map<String, String> tags);

    /**
     * 获取分布统计
     * 
     * @param name 指标名称
     * @param tags 标签
     * @return 分布统计
     */
    DistributionStatistics getDistributionStatistics(String name, Map<String, String> tags);

    /**
     * 获取所有指标名称
     * 
     * @return 指标名称集合
     */
    Set<String> getMetricNames();

    /**
     * 获取指标的所有标签
     * 
     * @param name 指标名称
     * @return 标签集合
     */
    Set<Map<String, String>> getMetricTags(String name);

    /**
     * 清空指标数据
     */
    void clearMetrics();

    /**
     * 导出指标数据
     * 
     * @param format 格式 (PROMETHEUS, JSON, CSV)
     * @return 导出内容
     */
    String exportMetrics(ExportFormat format);

    /**
     * 获取系统指标
     * 
     * @return 系统指标
     */
    SystemMetrics getSystemMetrics();

    /**
     * 获取应用指标
     * 
     * @return 应用指标
     */
    ApplicationMetrics getApplicationMetrics();

    /**
     * 记录自定义事件
     * 
     * @param eventName 事件名称
     * @param properties 事件属性
     */
    void recordEvent(String eventName, Map<String, Object> properties);

    /**
     * 开始计时
     * 
     * @param name 计时器名称
     * @param tags 标签
     * @return 计时器样本
     */
    TimerSample startTimer(String name, Map<String, String> tags);
}
